Norma de uso de la estrategia de ramificación de la plataforma CI/CD corporativa

Ámbito de aplicación de la norma

La Junta de Andalucía tiene como objetivo estratégico la estandarización de las herramientas y normas corporativas para la homogeneización del ciclo de vida del desarrollo de un producto software, promoviendo las prácticas DevSecOps, por lo que el uso de la estrategia de ramificación se extiende a todos los equipos de desarrollo de la ADA que utilicen la Plataforma de CI/CD corporativa.

Por tanto, todo sistema que:

• se encuentre en el Proceso de Transición a DevSecOps, DEBE utilizar la estrategia de ramificación de la Plataforma de CI/CD corporativa.
• se encuentre operativo o en desarrollo para ser desplegado en las infraestructuras de despliegue de la ADA, utilizando el modelo DevSecOps impulsado por el Servicio de Gobierno TI y Calidad, DEBE utilizar la estrategia de ramificación de la Plataforma de CI/CD corporativa.
• sea de nuevo desarrollo se RECOMIENDA que utilice la estrategia de ramificación de la Plataforma de CI/CD corporativa.
• cualquier otro sistema de información de la ADA, teniendo en cuenta sus posibles restricciones tecnológicas o presupuestarias, se RECOMIENDA que utilice la estrategia de ramificación de la Plataforma de CI/CD corporativa.

Puedes conocer en esta sección cómo se marca la obligatoriedad de cumplimiento de las directrices que componen la norma.

Uso y permisos de la estrategia de ramificación de la Plataforma CI/CD corporativa

DIR_01 Uso de estrategia de ramificación

OBLIGATORIO Los Sistemas de Información que utilicen la Plataforma de CI/CD corporativa DEBEN seguir la estrategia de ramificación definida en esta norma y la/s guía/s asociada/s a la misma.

La guía para seguir la estrategia de ramificación se describe en Estrategia de ramificación.

DIR_02 Roles y permisos de usuarios

OBLIGATORIO En la estrategia de ramificación los permisos de usuarios que afectan son los que se refieren a la gestión de ramas, fusiones y solicitudes de fusión.

El detalle sobre estos permisos y los roles a los que afectan se describen en el apartado Roles y permisos de usuarios de la guía Cómo se gestionan los permisos en el repositorio de código corporativo.

Gestión de ramas

DIR_03 Ramas de larga duración y su uso

OBLIGATORIO Las ramas de larga duración en el repositorio de código corporativo son aquellas que mantendrán una base estable para el desarrollo de software.

Como mínimo existirán las siguientes ramas:

• main: Rama principal de desarrollo. Contiene la versión más actualizada con estado estable. Es la rama a partir de la cual se derivan y fusionan otras ramas para desarrollar nuevas características o marcar hitos.
• test: Rama que representa el estado del código en entorno de Test.
• pre: Rama que representa el estado del código en entorno de Preproducción.
• pro: Rama que representan el estado del código en entorno de Producción.

Pueden existir ramas por entorno adicionales, dependiendo del número de entornos del que disponga del sistema de información, pero todas tendrán la misma consideración.

DIR_04 Ramas protegidas

OBLIGATORIO Las ramas de larga duración estarán configuradas como protegidas en el repositorio de código corporativo, por lo que cualquier cambio en estas ramas solo podrá ser solicitado vía solicitud de fusión (MR, Merge Request).

DIR_05 Ramas temporales y su uso

OBLIGATORIO Las ramas temporales se usarán para el desarrollo de características o correcciones.

Estas ramas proporcionaran un entorno aislado para trabajar en cambios sin afectar el flujo de trabajo principal del proyecto.

Podrán existir las siguientes ramas temporales:

• feature/<nombre de la funcionalidad>: rama que se crea específicamente para desarrollar una nueva característica o funcionalidad. Esta rama solo puede ser creada a partir de la rama main.
• release/x.y.z: rama de versión, creada automáticamente a partir de un tag especifico cuando se activa el proceso de integración continua. Esta rama se utilizará para fusionarse con cada rama que represente un entorno. Esta rama podrá ser desplegada en los entornos de test, pre y pro. Para versionar de forma correcta el código, se tienen que seguir las directrices marcadas en Política de versionado software.
• test/x.y.z: rama de test, creada a partir de un tag especifico de la rama main, que se utilizará para fusionar con la rama test disparando así el despliegue en dicho entorno. 
• hotfix/<nombre de la funcionalidad>: rama donde se realizan los cambios que sean necesarios para solucionar errores en la rama de pro.
• hotfix/x.y.z: rama de versión, creada a partir de un tag especifico de la rama hotfix, que se utilizará para fusionar con la rama pro, disparando así el despliegue en dicho entorno. Además, para realizar pruebas específicas, esta rama podrá ser desplegada en los entornos de test, pre y pro.

DIR_06 Eliminación de las ramas temporales

OBLIGATORIO Las ramas temporales serán eliminadas en cuanto se apruebe una fusión con la rama correspondiente.

DIR_07 Corrección de errores en el entorno de producción

OBLIGATORIO La corrección de errores en el entorno de producción se realizará a través de una feature o creando una rama hotfix

En el caso que se detecten errores en el entorno de Producción, se aconsejan seguir los siguientes pasos:

Opción preferente:

• Se debe crear una rama feature/<nombre del problema> desde main, donde se realizarán las correcciones correspondientes al error.
• Seguir el flujo normal de trabajo para desplegar estos cambios en producción.

Opción (hotfix):

• Crear una rama de tipo hotfix/<nombre de la funcionalidad a corregir> desde la rama pro, donde se realizarán las correcciones y pruebas correspondientes al error.
• Crear un tag x.y.z-hotfix desde la rama hotfix. Este paso activa el proceso CI generará de forma automática la rama hotfix/x.y.z. Esta rama podrá ser desplegada en cualquier entorno.
• Solicita una solicitud de fusión (MR) para fusionar la rama hotfix/x.y.z con la rama pro.
• Crear una rama de con nomenclatura feature-hotfix/<nombre de la funcionalidad a corregir> y mediante la técnica de Cherry pick actualizar esta rama con los cambios realizados en la rama hotfix.
• Solicitar un MR para actualizar la rama main con los cambios realizados en la rama feature-hotfix/<nombre de la funcionalidad a corregir>. Como ya se tiene actualizada la rama main seguir el flujo de trabajo normal.

Nomenclatura

DIR_08  Nomenclatura del etiquetado (Tag) de la rama main

OBLIGATORIO Los tags deben tener la siguiente nomenclatura en función del entorno donde se quiera desplegar el software.

Esta nomenclatura será:

• x.y.z-test: Para despliegue solo en el entorno de test. El proceso de CI creará de forma automática la rama test/x.y.z.
• x.y.z-release: Para despliegue principalmente en los entorno de pre y pro. El proceso de CI creará de forma automática la rama release/x.y.z.
  Ocasionalmente, esta rama también podrá ser utilizada para desplegar en el entorno de test si es necesario.

DIR_09 Nomenclatura de ramificación

OBLIGATORIO Las ramas deben seguir la siguiente nomenclatura

• Ramas de características o feature: feature/<nombre de la funcionalidad>
• Ramas para hotfix: hotfix/<nombre del problema>
• Rama para las versiones: release/x.y.z

Otras recomendaciones

DIR_10 División estructural de los cambios

RECOMENDADO Se debe seguir una política clara y simple en la gestión de los commits

Para seguir una técnica de commits que sea limpia y entendible por todo el equipo de desarrollo se deben tener en cuenta los siguientes aspectos:

• Regla Cardinal: Asegurarse de un cambio lógico por commit.
• Evitar:
  • Mezclar cambios de espacios en blanco con cambios de código funcional.
  • Mezclar dos cambios funcionales no relacionados.
  • Enviar grandes nuevas características en un solo commit gigante.
• Regla Básica: Si un cambio puede dividirse en commits separados, debería hacerlo.

DIR_11 Información en los mensajes de commit

RECOMENDADO Todo commit debe ir documento de un mensaje claro de los cambios realizados.

Qué Hacer:

• Describir el problema original y cómo se está solucionando.
• Documentar por qué se está haciendo un cambio.
• Incluir información suficiente para los revisores.
• Usar un lenguaje claro y conciso.

Qué No Hacer:

• Suponer que el revisor comprende el problema original.
• Suponer que el código es evidente por sí solo.
• Incluir comentarios específicos del conjunto de parches.
   

DIR_12 Inclusión de referencias externas

RECOMENDADO Inclusión de referencias externas.

Utilizar metadatos para uso de máquinas, como 'Change-id', 'Bug', 'Blueprint', etc.

Asegurarse de que todos los metadatos dirigidos a máquinas estén agrupados al final del mensaje de commit.

Seguir convenciones estándar para referenciar errores, blueprints y otros recursos externos.

DIR_13 Resumen de la estructura del mensaje de commit

RECOMENDADO El mensaje del commit deberá estar estructurado.

• Proporcionar una breve descripción del cambio en la primera línea (limitado a 50 caracteres).
• Insertar una línea en blanco después de la primera línea.
• Proporcionar descripciones detalladas del cambio en líneas subsecuentes, con un límite de 72 caracteres.
• Idioma de los commits preferiblemente en español.
  Ejemplo:
       [Tarea #121] Añadir autenticación de usuario
       [Tarea #122] Actualización del servicio de pagos